<!DOCTYPE html PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN" "http://www.w3.org/TR/html4/loose.dtd">
<html><meta http-equiv="Content-Type" content="text/html; charset=utf-8">
<title>C system error results - Boost.Outcome documentation</title>
<link rel="stylesheet" href="../../../css/boost.css" type="text/css">
<meta name="generator" content="Hugo 0.52 with Boostdoc theme">
<meta name="viewport" content="width=device-width,initial-scale=1.0"/>

<link rel="icon" href="../../../images/favicon.ico" type="image/ico"/>
<body><div class="spirit-nav">
<a accesskey="p" href="../../../experimental/c-api/from-c.html"><img src="../../../images/prev.png" alt="Prev"></a>
    <a accesskey="u" href="../../../experimental/c-api/from-c.html"><img src="../../../images/up.png" alt="Up"></a>
    <a accesskey="h" href="../../../index.html"><img src="../../../images/home.png" alt="Home"></a><a accesskey="n" href="../../../experimental/c-api/from-c/declare.html"><img src="../../../images/next.png" alt="Next"></a></div><div id="content">
  <div class="titlepage"><div><div><h1 style="clear: both">C system error results</h1></div></div></div>
  <p>In v2.2.11, C Result support went from second tier to first tier status, and
now you can create, query and manipulate a subset of Result types entirely from
within C by including <code>&lt;boost/outcome/experimental/result.h&gt;</code>.</p>

<p>The subset supported are those <code>result&lt;T, E&gt;</code> which are <a href="../../../experimental/status_result.html">a <code>status_result&lt;T&gt;</code></a>
i.e. the <code>E</code> is hardcoded to <code>experimental::error</code> which is the type erased runtime
polymorphic holder for any errored <code>status_code</code> whose payload is not bigger
than an <code>intptr_t</code>. This is the most useful subset of Outcome Experimental&rsquo;s
possible Result types, allowing arbitrary custom error coding schemes from
any unknown source to work seamlessly with all others, including errors from
the system or third party libraries.</p>

<p>The operations available to C are:</p>

<dl>
<dt><code>BOOST_OUTCOME_C_DECLARE_RESULT_SYSTEM(ident, T)</code>
<dd>Declares to C a <code>status_result<T></code> type uniquely
identified by <code>ident</code>. <code>T</code> is available at the
member variable <code>.value</code>, and <code>struct cxx_status_code_system</code>
is available at the member variable <code>.error</code>. If in C++,
implements C extern functions for making successful and failure results
of this type. If you call this from within
C++, make SURE it is not within a <code>extern "C"</code> block!

<dt><code>BOOST_OUTCOME_C_RESULT_SYSTEM(ident)</code>
<dd>A reference to a previously declared <code>status_result</code> type with
unique <code>ident</code>.

<dt><code>BOOST_OUTCOME_C_MAKE_RESULT_SYSTEM_SUCCESS(ident, expr)</code> (needs C++ counterpart linked into final binary)
<dd>This invokes the aforementioned extern function which creates a <code>status_result</code>
with a successful value of type <code>T</code>.
<dt><code>BOOST_OUTCOME_C_MAKE_RESULT_SYSTEM_FAILURE_POSIX(ident, expr)</code> (needs C++ counterpart linked into final binary)
<dd>This invokes the aforementioned extern function which creates a <code>status_result</code>
with a failure of type <code>posix_code</code> representing a POSIX <code>errno</code>.
<dt><code>BOOST_OUTCOME_C_MAKE_RESULT_SYSTEM_FAILURE_SYSTEM(ident, expr)</code> (needs C++ counterpart linked into final binary)
<dd>This invokes the aforementioned extern function which creates a <code>status_result</code>
with a failure of type <code>posix_code</code> representing a POSIX <code>errno</code>
if on POSIX; if on Windows then a failure of type <code>win32_code</code>
representing a Win32 error code from a Windows API.

<br><br>
<dt><code>BOOST_OUTCOME_C_RESULT_HAS_VALUE(r)</code>
<dd>Evaluates to 1 (true) if the input <code>result</code> has a value.

<dt><code>BOOST_OUTCOME_C_RESULT_HAS_ERROR(r)</code>
<dd>Evaluates to 1 (true) if the input <code>result</code> has an error.

<dt><code>BOOST_OUTCOME_C_RESULT_ERROR_IS_ERRNO(r)</code>
<dd>Evaluates to 1 (true) if the input <code>result</code>'s error value
is a code in the POSIX <code>errno</code> domain.
<br><br>
<dt><code>BOOST_OUTCOME_C_RESULT_SYSTEM_TRY(expr)</code>
<dd>If the <code>status_result</code> returned by <code>expr</code> is
errored, exit the current function returning the result. This obviously
requires that the return type of the current function matches that of <code>
expr</code>.

<dt><code>BOOST_OUTCOME_C_RESULT_SYSTEM_TRY(cleanup, expr)</code>
<dd>Same as the above, but execute <code>cleanup</code> just before exiting the function
if returning failure.

<dt><code>BOOST_OUTCOME_C_RESULT_SYSTEM_TRY(var, cleanup, expr)</code>
<dd>Same as the above, but set <code>var</code> equal to the result's <code>.value</code> on success.

<dt><code>BOOST_OUTCOME_C_RESULT_SYSTEM_TRY(var, ident, cleanup, expr)</code>
<dd>Same as the above, but use <code>ident</code> as the return type instead. This allows
the return type of the calling function to differ from that of <code>expr</code>.
<br><br>
<dt><code>BOOST_OUTCOME_C_DECLARE_RESULT_SYSTEM_FROM_ENUM(ident, enum_name, uuid, {enum mapping-sequence, ...})</code>
<dd>This declares to C an extern function which creates a <code>status_result</code>
from a C enum. If in C++, it implements a <code>quick_status_code_from_enum</code> for
the C enum and the associated extern function, and you will need to supply <code>uuid</code>
and the appropriate enum value mapping sequence <a href="../../../experimental/worked-example.html">
as per the <code>quick_status_code_from_enum</code> documentation</a>.
<dt><code>BOOST_OUTCOME_C_MAKE_RESULT_SYSTEM_FROM_ENUM(ident, enum_name, expr)</code> (needs C++ counterpart linked into final binary)
<dd>This invokes the aforementioned extern function which creates a <code>status_result</code>
from a C enum.
</dl>

<p>The operations available to C++ are:</p>

<dl>
<dt><code>BOOST_OUTCOME_C_TO_RESULT_SYSTEM_CODE(ident, status_code&lt;T&gt;)</code>
<dd>Returns a previously declared C Result from its matching C++ <code>status_code</code>.
NOTE that the destructor of the C++ status code is NOT called. If this is important
to your status code, it is 100% on you to ensure that your C Result reenters a C++
Result at the end of its lifetime.

<dt><code>to_result(any C Result)</code>
<dd>This is an overloaded C++ free function which returns the C++ status_code&lt;T&gt;
matching its input C Result.
</dl>

<p>Using the above you can write C code using Outcome.Experimental&rsquo;s Result type
quite effectively. Let&rsquo;s look at an example of use next.</p>


        </div><p><small>Last revised: July 17, 2024 at 17:54:05 &#43;0100</small></p>
<hr>
<div class="spirit-nav">
<a accesskey="p" href="../../../experimental/c-api/from-c.html"><img src="../../../images/prev.png" alt="Prev"></a>
    <a accesskey="u" href="../../../experimental/c-api/from-c.html"><img src="../../../images/up.png" alt="Up"></a>
    <a accesskey="h" href="../../../index.html"><img src="../../../images/home.png" alt="Home"></a><a accesskey="n" href="../../../experimental/c-api/from-c/declare.html"><img src="../../../images/next.png" alt="Next"></a></div></body>
</html>
